---
title: OpenAI Agents SDK TypeScript
description: The OpenAI Agents SDK for TypeScript enables you to build agentic AI apps in a lightweight, easy-to-use package with very few abstractions.
---

import { LinkCard } from '@astrojs/starlight/components';
import { Code } from '@astrojs/starlight/components';
import Hero from '../../../components/Hero.astro';

import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw';

<Hero>
  <Fragment slot="title">빠른 시작</Fragment>
  <Fragment slot="description">
    단 몇 분 만에 첫 에이전트를 만들 수 있습니다
  </Fragment>
  <Fragment slot="cta">시작하기</Fragment>
</Hero>

## 개요

[OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js)는
아주 적은 추상화로 가볍고 사용하기 쉬운 패키지에서 에이전트형 AI 앱을 구축할 수 있게 합니다. 이는 이전
에이전트 실험작인
[Swarm](https://github.com/openai/swarm/tree/main)의 프로덕션급 업그레이드이며, [Python 버전](https://github.com/openai/openai-agents-python)도 제공합니다. Agents SDK는 아주
작은 개수의 기본 구성 요소를 제공합니다:

- **에이전트**: instructions와 tools가 장착된 LLM
- **핸드오프**: 특정 작업에 대해 다른 에이전트에 위임할 수 있게 함
- **가드레일**: 에이전트 입력을 검증할 수 있게 함

TypeScript와 결합하면, 이러한 기본 구성 요소만으로도 도구와 에이전트 간의 복잡한 관계를 표현하고,
가파른 학습 곡선 없이 실사용 애플리케이션을 구축할 수 있습니다. 또한 SDK에는
에이전트 플로우를 시각화하고 디버그할 수 있는 **트레이싱**이 내장되어 있으며,
이를 평가하고 애플리케이션에 맞게 모델을 파인튜닝하는 데에도 활용할 수 있습니다.

## Agents SDK 사용 이유

SDK는 두 가지 설계 원칙을 따릅니다:

1. 사용할 가치가 있을 만큼 충분한 기능을 제공하되, 빠르게 익힐 수 있도록 기본 구성 요소는 최소화
2. 기본값만으로도 잘 작동하지만, 동작을 세밀하게 커스터마이즈 가능

SDK의 주요 기능은 다음과 같습니다:

- **에이전트 루프**: 도구 호출, 결과를 LLM으로 전송, LLM이 종료될 때까지 루프를 처리하는 내장 루프
- **TypeScript 우선**: 새로운 추상화를 배울 필요 없이 언어 기능만으로 에이전트를 오케스트레이션하고 체이닝
- **핸드오프**: 여러 에이전트 간의 조정과 위임을 위한 강력한 기능
- **가드레일**: 에이전트와 병렬로 입력 검증과 점검을 수행하고, 실패 시 조기 중단
- **함수 도구**: 어떤 TypeScript 함수든 자동 스키마 생성과 Zod 기반 검증으로 도구로 변환
- **트레이싱**: 워크플로를 시각화, 디버그, 모니터링하고 OpenAI의 평가, 파인튜닝, 디스틸레이션 도구를 활용
- **실시간 에이전트**: 자동 인터럽션(중단 처리) 감지, 컨텍스트 관리, 가드레일 등 강력한 음성 에이전트 구축

## 설치

```bash
npm install @openai/agents zod@3
```

## Hello World 예제

<Code lang="typescript" code={helloWorldExample} title="Hello World" />

(_이 예제를 실행하려면 `OPENAI_API_KEY` 환경 변수를 설정하세요_)

```bash
export OPENAI_API_KEY=sk-...
```
